﻿using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace lucere.analysis
{
    /// <summary> This abstract class defines methods to iterate over a set of non-decreasing
    /// doc ids. Note that this class assumes it iterates on doc Ids, and therefore
    /// {@link #NO_MORE_DOCS} is set to {@value #NO_MORE_DOCS} in order to be used as
    /// a sentinel object. Implementations of this class are expected to consider
    /// {@link Integer#MAX_VALUE} as an invalid value.
    /// </summary>
    public interface IDocIdSetIterator : IEnumerator<int>
    {
        /// <summary> Advances to the next document in the set and returns the doc it is
        /// currently on, or {@link #NO_MORE_DOCS} if there are no more docs in the
        /// set.<br/>
        /// 
        /// <b>NOTE:</b> in 3.0 this method will become abstract, following the removal
        /// of {@link #Next()}. For backward compatibility it is implemented as:
        /// 
        /// <pre>
        /// public int nextDoc() throws IOException {
        /// return next() ? doc() : NO_MORE_DOCS;
        /// }
        /// </pre>
        /// 
        /// <b>NOTE:</b> after the iterator has exhausted you should not call this
        /// method, as it may result in unpredicted behavior.
        /// 
        /// </summary>
        /// <since> 2.9
        /// </since>
        int NextDoc();

        /// <summary> Advances to the first beyond the current whose document number is greater
        /// than or equal to <i>target</i>. Returns the current document number or
        /// {@link #NO_MORE_DOCS} if there are no more docs in the set.
        /// <p/>
        /// Behaves as if written:
        /// 
        /// <pre>
        /// int advance(int target) {
        /// int doc;
        /// while ((doc = nextDoc()) &lt; target) {
        /// }
        /// return doc;
        /// }
        /// </pre>
        /// 
        /// Some implementations are considerably more efficient than that.
        /// <p/>
        /// <b>NOTE:</b> certain implemenations may return a different value (each
        /// time) if called several times in a row with the same target.
        /// <p/>
        /// <b>NOTE:</b> this method may be called with {@value #NO_MORE_DOCS} for
        /// efficiency by some Scorers. If your implementation cannot efficiently
        /// determine that it should exhaust, it is recommended that you check for that
        /// value in each call to this method.
        /// <p/>
        /// <b>NOTE:</b> after the iterator has exhausted you should not call this
        /// method, as it may result in unpredicted behavior.
        /// <p/>
        /// <b>NOTE:</b> in 3.0 this method will become abstract, following the removal
        /// of {@link #SkipTo(int)}.
        /// 
        /// </summary>
        /// <since> 2.9
        /// </since>
        int Advance(int paramInt);
    }
}
